home *** CD-ROM | disk | FTP | other *** search
/ Cream of the Crop 21 / Cream of the Crop 21 (Terry Blount) (October 1996).iso / program / libkb100.zip / LIBKB-1.00 / KB.DOC < prev    next >
Text File  |  1996-07-23  |  19KB  |  511 lines
  1. Markus F.X.J. Oberhumer <markus.oberhumer@jk.uni-linz.ac.at>
  2.  
  3.  
  4. ===============================================================================
  5. 1. Introduction
  6. ===============================================================================
  7.  
  8. libkb is a free, advanced and portable low-level keyboard library
  9. for MSDOS and Linux.
  10.  
  11. It has the following highlights:
  12.  
  13. - it's advanced
  14.     Allows access to ALL keys and ALL combinations of them.
  15.     You can individually test left and right Shift and Control,
  16.     Alt and AltGr, cursor keys, the keypad and everything else
  17.     you always wanted. Also handles Pause key and Control-Break.
  18.     Supports virtual terminal switching under Linux.
  19.     Ideal for games and all applications that want
  20.     total control over the keyboard.
  21.  
  22. - it's practical
  23.     Builtin kbhit()/getkey() like interface that allows you
  24.     to easily read the keyboard for text input, highscore names
  25.     or cheat codes.
  26.  
  27. - it's portable
  28.     Works under MSDOS and Linux.
  29.     Written entirely in C without assembler code.
  30.     Supports Borland C v3.1 and 4.0 (16 bit), Watcom C v10.5 (32 bit),
  31.     djgpp v1 + v2 (32 bit) and Linux gcc.
  32.  
  33. - it's safe
  34.     The library tries to remove its keyboard handler when a program
  35.     terminates or crashes. For this purpose it installs some intelligent
  36.     signal handlers and uses the atexit() function to achieve
  37.     a maximum of robustness.
  38.     Support for an emergency-exit key sequence is provided - this is 
  39.     really useful during development.
  40.     Interrupt handler memory in virtual memory environments is locked.
  41.  
  42. - it's easy to use
  43.     The core interface consists of only a handful of functions and variables.
  44.     Care has been taken not to pollute the global namespace.
  45.     Example programs are included as well.
  46.  
  47. - it's free
  48.     Comes with full source code and documentation. And yes, you can
  49.     use it in your commercial applications (no GPL restrictions).
  50.  
  51.  
  52. And the following restrictions:
  53.     
  54. - it's americanized
  55.     As the library hooks the keyboard interrupt, individual
  56.     keys read with kb_getkey() return hardcoded ASCII values
  57.     for the scancodes. These are valid for American keyboards only,
  58.     e.g. on a German keyboard Y and Z seem exchanged.
  59.     In the beginning I had planned to include support for local key
  60.     mappings, but this soon started to become too complex.
  61.     Most advanced games suffer this problem.
  62.     
  63. - it's software
  64.     Unfortunately the keyboard controller hardware was not
  65.     designed with heavy action in mind. This means that there are
  66.     various key combinations that cannot be pressed at the
  67.     same time - the keyboard controller just won't handle them.
  68.     Nevertheless libkb makes all information the hardware is
  69.     able to generate available to an application and the test
  70.     program shows you when an 'overflow' occurs so that you
  71.     can setup safe default keys for your games.
  72.     
  73.  
  74.  
  75. ===============================================================================
  76. 2. Documentation
  77. ===============================================================================
  78.  
  79. The basic usage of the library is very simple:
  80.  
  81.   - install the keyboard handler with kb_install(0)
  82.   - update the keyboard with kb_update() 
  83.   - access single keys with kb_key(KB_SCAN_xxx)
  84.   - you also have quick access to the shift flags with kb_shift()
  85.   - if you want to read textual input, use kb_getkey()
  86.   - if you want to switch back to standard keyboard behavior,
  87.     call kb_remove(). This will be done for you automatically 
  88.     when the program terminates or crashes.
  89.  
  90.  
  91. The flags
  92. ---------
  93.  
  94.   Some flags can be passed to kb_install(). Not all of them 
  95.   are foolproof and you should know what you are doing when
  96.   you are using them. Consider taking a look at the source code
  97.   for additional information.
  98.  
  99.  
  100.   Flags that disable default safety features:
  101.  
  102.     KB_FLAG_NO_ATEXIT 
  103.       Do not install an atexit() handler.
  104.  
  105.     KB_FLAG_NO_SIGNAL
  106.       Do not install signals handlers.
  107.  
  108.     KB_FLAG_NO_LOCK
  109.       Do not lock interrupt memory.
  110.  
  111.  
  112.   Flags that enable extra safety features (useful in development):
  113.  
  114.     KB_FLAG_SIGINT
  115.       raise SIGINT on Control-C
  116.  
  117.     KB_FLAG_EMERGENCY_EXIT
  118.       enable emergency exit: raise SIGINT on LControl-RControl-C and
  119.         exit if the SIGINT-handler returns. Under MSDOS this causes
  120.         an exit from within an interrupt handler which can be 
  121.         somewhat dangerous, but it seems to work though.
  122.         You should always setup a SIGINT handler when using this.
  123.  
  124.     KB_FLAG_EMERGENCY_SIGALRM
  125.       enable SIGALRM emergency exit (this is mainly useful for Linux):
  126.         If your program has a bug and it doesn't call kb_update(),
  127.         the machine would lock under Linux cause KB_FLAG_EMERGENCY_EXIT
  128.         also relies on kb_update(). When this flag is enabled, the
  129.         alarm() timer is used to raise SIGALRM if kb_update() is not 
  130.         called for more than 30 seconds. You should not use SIGALRM
  131.         for other purposes when using this flag. 
  132.  
  133.  
  134.   Misc. flags (probably not very useful):
  135.  
  136.     KB_FLAG_LINUX_NO_VT
  137.       Linux: virtual terminal switching is disabled
  138.  
  139.     KB_FLAG_LINUX_VT_NO_KEY
  140.       Linux: release all keys after virtual terminal switching
  141.  
  142.     KB_FLAG_DJGPP_NO_RM
  143.       djgpp: do not install an additional real mode handler
  144.  
  145.     KB_FLAG_REPEAT_OFF
  146.       turn off key repeat for kb_getkey()
  147.  
  148.  
  149. The keycodes
  150. ------------
  151.  
  152.   The keycode-tables were obtained as a result of investigating
  153.   the output of kb_bios_getkey() under MSDOS. They are portable
  154.   across all platforms and will remain fixed.
  155.   The keycode is computed by passing the result of kb_keypress()
  156.   or kb_keypeek() to kb_keycode(). You can write your own conversion 
  157.   routine if you want to add support for local key mappings.
  158.   
  159.  
  160. Notes on building libkb
  161. -----------------------
  162.  
  163.   It is really IMPORTANT to check your compiler flags so that 
  164.   code will be generated that does not insert stack overflow checks !
  165.  
  166.   You should also use a high optimization level in order to use
  167.   as many CPU registers as possible and avoid memory access 
  168.   inside interrupt- and signal handlers.
  169.  
  170.  
  171. Notes on using libkb with other libraries
  172. -----------------------------------------
  173.  
  174. - Linux + svgalib 1.2.x
  175.   Though svgalib chains all signals it catches, it does a lot of low-level
  176.   things to support virtual terminal switching while in graphics mode.
  177.   So be nice and call kb_install() AFTER svgalib has been initialized.
  178.   Note that the real initialization does not happen in vga_init() but
  179.   the first time you call vga_setmode(). 
  180.   svgalib also doesn't like if you redirect stderr, and you should
  181.   not use keyboard_init() from <vgakeyboard.h> after kb_install().
  182.  
  183.  
  184. Signals (advanced feature)
  185. -------
  186.  
  187.   To achieve a maximum of robustness, libkb catches (almost)
  188.   all signals that cause an exit by default (if a signal is 
  189.   ignored libkb ignores that signal as well).
  190.   If a catched signal gets raised, the signal handler removes
  191.   the keyboard handler and chains to the handler it found active
  192.   at installation time.
  193.  
  194.   The libkb signal handler expects from the old (chained) handler
  195.     - that the program terminates, or
  196.     - that the application gets informed that the keyboard is removed
  197.  
  198.   You probably don't need to worry 
  199.     - if you setup your signals before kb_install()
  200.     - if you want to temporary change a signal after kb_install()
  201.     - if you want to ignore a signal after kb_install()
  202.  
  203.   You could find the signal interface useful 
  204.     - if you want to test if libkb installed a handler for a specific signal
  205.     - if you want libkb to catch additional signals
  206.     - if you want to set your own signal handler after kb_install() and
  207.       want to chain to the one of libkb
  208.  
  209.  
  210. Memory locking (advanced feature)
  211. --------------
  212.  
  213.   Memory locking functions have been made public as they are of
  214.   potential use for all interrupt routines.
  215.   They can be used independently from the rest of the library.
  216.  
  217.  
  218. The Operating System (OS) and BIOS functions
  219. --------------------------------------------
  220.  
  221.   Please don't get confused:
  222.     the OS and BIOS layers have nothing to do with the keyboard
  223.     handler. They mainly act as a portability wrapper and are
  224.